home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 6 / CU Amiga Magazine's Super CD-ROM 06 (1996)(EMAP Images)(GB)(Track 1 of 4)[!][issue 1997-01].iso / system / play16 / play16.doc < prev    next >
Text File  |  1996-02-04  |  23KB  |  530 lines
  1.  
  2. ---------------------------------------------------------------------------
  3. -- Play16 version 1.6 (04.02.96) - a versatile soundplayer for the Amiga --
  4. ---------------------------------------------------------------------------
  5.  
  6. Features in brief
  7. -----------------
  8.  - autodetects and plays several soundfiles, up to 16 bit / 56 kHz / stereo
  9.  - full Workbench support (but not Intuition and no GUI)
  10.  - always correct playback speed, even for sounds >28 kHz
  11.  - realtime playback from harddisk, optimized assembler routines
  12.  - optional 14 bit output (less noise but not as good as true 16 bit)
  13.  - automatic or manual audio filter control
  14.  - plays mono sounds on *both* channels, not only on the left one
  15.  - plays (and loops) files that are larger than memory
  16.  - preloading for exactly timed start of playback
  17.  - fast uLaw decompression
  18.  - system friendly audio channel allocation
  19.  - optionally dump the output into a file (can be used to convert sounds)
  20.  - supported Filetypes are:
  21.  
  22.    * Microsoft RIFF-WAVE  (.WAV)  mono/stereo, 8/16 bit, linear/uLaw/ADPCM
  23.    * Creative Voice File  (.VOC)  mono/stereo, 8/16 bit, linear
  24.    * Sun/NeXT Audio       (.AU)   mono/stereo, 8/16 bit, linear/uLaw
  25.    * MacroSystem Audio    (.MAUD) mono/stereo, 8/16 bit, linear/uLaw
  26.    * Apple/SGI/Amiga AIFF (.AIFF) mono/stereo, 8/16 bit, linear
  27.    * Amiga IFF-8SVX       (.IFF)  mono/stereo, 8    bit, linear/FibDelta
  28.    * Any raw sound data as long as it matches one of the following:
  29.      -  8 bit signed
  30.      -  8 bit unsigned
  31.      - 16 bit signed, Intel format    (LSB first)
  32.      - 16 bit signed, Motorola format (MSB first)
  33.  
  34.     - supported output devices are:
  35.  
  36.    * Native Amiga chipset (Paula)  8 bit
  37.    * Native Amiga chipset (Paula) 14 bit
  38.    * Native Amiga chipset (Paula) 14 bit calibrated (Christian Buchner)
  39.    * MacroSystem Maestro Pro      16 bit 44.1kHz and 48kHz only
  40.    * IFF-8SVX file dump            8 bit
  41.  
  42. ========================== Section 1: Quick start =========================
  43.  
  44. What do I need to use Play16?
  45. -----------------------------
  46. Any Amiga running Kickstart/Workbench 2.04 or greater.
  47.  
  48. To use the calibrated 14 bit output you need a valid CyberSound preferences
  49. file in your ENVARC: directory. If you don't have one already it can be
  50. generated with Christian's calibration package included in this distribution.
  51.  
  52. Maestix.library V39 or higher is required to use the MPro board for output.
  53.  
  54. Where do I find the latest version?
  55. -----------------------------------
  56.  - FIDONET: Amiga Venture BBS, Germany (2:2432/350)
  57.  - AMINET:  mus/play
  58.  - WWW:     http://linux.rz.fh-hannover.de/~wenzel/Play16/
  59.  
  60. further I recommend to have a look at the following packages:
  61.  
  62. CyberSound:
  63.  - AMINET:  disk/cdrom/14Bit_CDPlayer.lha
  64.  
  65. Maestix:
  66.  - AMINET:  util/libs/Maestix39_00.lha
  67.  
  68. How do I use it?
  69. ----------------
  70. From CLI:       Simply type "Play16 <filename>" and that's it!
  71. From Workbench: Just doubleclick on it's icon. A filerequester will pop up.
  72.  
  73. All possible options will be explained later. If you set none of them, the
  74. defaults will be used.
  75.  
  76.  
  77.  
  78.  
  79. ==================== Section 2: Background information ====================
  80.  
  81. What does it do?
  82. ----------------
  83. Basically, Play16 is capable of playing uncompressed and _some_ compressed
  84. soundfiles through Amiga's standard audio device or an increasing number of
  85. alternative devices. If the actual resolution or playback rate exceeds that
  86. of the Amiga hardware, realtime conversion is done so that the sound is
  87. being played back correctly.
  88.  
  89. You can even play 16 bit / 44.1 kHz sounds, providing all parts of
  90. your system can keep up with the high data transfer rate and lots
  91. of calculations needed for this task. (In this case an accelerated
  92. Amiga is recommended :-)
  93.  
  94. The two audio channels at each side can be linked to perform as a single
  95. 14 bit channel (subranging). Again, this swallows lots of computing power.
  96.  
  97. Anyway, an Amiga 3000-16MHz is fast enough to play an uncompressed soundfile
  98. with full 44.1kHz/14bit output (productivity) directly from harddisk !!!
  99.  
  100. I don't want Play16 to be a program that plays each and every exotic format
  101. that exists somewhere. However, I intend to support as many popular file
  102. types as possible.
  103.  
  104.  
  105. Why Play16?
  106. -----------
  107. I didn't find any CLI based program to play back 16 bit recordings, on a
  108. standard Amiga, so I decided to write one myself.
  109. 16 bit soundcards are becoming more and more popular, especially on the
  110. PC. The common file format over there is Microsoft's (yuck! :)) RIFF-
  111. WAVE format.
  112.  
  113.  
  114. Why CLI based and no GUI?
  115. -------------------------
  116. There are so many GUI based directory utilities, simply use Play16 as an
  117. external player. Consult the manual of your software package on how to
  118. do it. Application example: Assign "Play16 <filename> PRELOAD" to a button
  119. called "Jingle". Select the desired soundfile and press the Jingle-button.
  120. Wait for the appropriate moment and hit the return key - here comes the
  121. sound! Nice when audio dubbing your home videos or even on parties :-)
  122.  
  123.  
  124. How does it work? (technical info)
  125. ----------------------------------
  126. The standard Amiga audio device is limited to 8 bit / 28 kHz playbck
  127. when using DMA. With the introduction of ECS the 28 kHz DMA barrier
  128. was broken - but only if the current displaymode was one with double
  129. scan rate like productivity. The reason for this is the dependency
  130. between video and audio DMA. If you don't have ECS or if you simply
  131. don't want to switch to Productivity just to listen to your desired
  132. sound, Play16 can halve the sample rate during playback.
  133.  
  134. Another way to archieve high output rates is using IRQ. This works no
  135. matter what the displaymode is. I've been experimenting on that long
  136. before I started writing Play16 but there was so much jitter that my
  137. current downsampling method sounds much better.
  138.  
  139. To play back even long sounds, the popular method of double buffering
  140. is used. Alternatively, all data can be loaded into memory before
  141. playback. This is useful when playing short sounds or when loading
  142. the sound from floppy disk or slow CD ROM.
  143.  
  144. The 14 bit output is archieved by setting the first channel on each
  145. side to volume 64 and the second to volume 1. The louder channel then
  146. plays the upper 8 bits as usual while the other channel plays the
  147. 6 most significant bits of the low byte synchronously. Because timing
  148. is very crucial in this case it is nessecary to write directly to
  149. hardware registers instead of using the audio.device. This method may
  150. not work on future amiga models if there ever will be any... :-/
  151.  
  152. Unfortunately, Amiga's DACs are not perfectly linear. A significant
  153. increase in sound quality can be archieved by calibrating each
  154. MSB conversion step individually for your machine. Christian Buchner's
  155. CyberSound system supports this kind of calibration. Play16 can load
  156. the preferences file generated by Christian's calibration program.
  157.  
  158. The MPro output uses the maestix.library by Richard Körber. Have a look
  159. at the Maestix package available on AMINET for further details.
  160.  
  161. =========================== Section 3: Options ============================
  162.  
  163. What options are provided?
  164. --------------------------
  165. There are three ways to specify the options, which are:
  166.  
  167.  CLI:       In the commandline, using standard AmigaOS 2.x template
  168.  Workbench: In the icon, using standard Amiga Workbench tooltype entries
  169.  General:   By setting environment variables. This is not possible for
  170.             all options yet.
  171.  
  172. If you are not familiar with the AmigaOS 2.x commandline template, see
  173. the examples below and consult the AmigaOS manual for furhter information.
  174. The tooltype entries are identical to the keywords you can specify in the
  175. commandline. Also, the environment variables have the same names and reside
  176. in ENV:Play16. 
  177.  
  178. Basic options: (All options marked with (*) have corresponding env-vars.)
  179.  
  180. VERBOSITY/N Sets the level of verbosity.
  181.             0: Just display the banner and error messages
  182.             1: Print additional information about the sound file,
  183.                allocated memory, etc.
  184.             2: Progress information
  185.             3: Debugging information (may look a bit weird :)
  186.             Default is level 0.
  187.  
  188. FAST/S      Do NOT automatically switch to half sample rate if the
  189.             soundfile's rate exceeds 28 kHz. Use this option when
  190.             running your Amiga in Productivity or similar display
  191.             modes.
  192.  
  193. HIFI/S      Obsolete since V1.4 but still included for compatibility
  194.             reasons. See "OUTPUT/K".
  195.  
  196. VOLUME/N    Set the playback volume. This works only for Paula8 output.
  197.  
  198. OUTPUT/K(*) Set Play16's output device. Possible options are:
  199.  
  200.  Paula8      Standard 8 bit output through Amiga hardware. This option
  201.              is the default.
  202.  
  203.  Paula14     Turn on the 14 bit output. Watch out! This is a nasty routine
  204.              that writes directly to some hardware registers. I've done
  205.              everything I can to prevent Play16 from interfering with
  206.              other running tasks in this case but you'll never know...
  207.              Use it with care!
  208.  
  209.  Paula14c    Same as Paula14 but using the calibration preferences for
  210.              much better sound quality. See Section 2 for details.
  211.  
  212.  MPro        Use MacroSystem's Maestro Pro board for output. 44.1kHz and
  213.              48kHz sounds only. For 44.1kHz output a valid and stable
  214.              signal has to be present on the standard input. See the
  215.              manuals of Maestix and the MPro board for further info.
  216.  
  217.  8SVX        Do not play the sound but create an IFF-8SVX file containing
  218.              the data. Basically this is the output generated by <Paula8>
  219.              redirected into a file. The filename will be the input file's
  220.              name with "iff" appended.
  221.  
  222.              WARNING: All limitations of <Paula8> apply here as well,
  223.              which are:
  224.              - Every 16 bit sound will be cropped to 8 bits resulting in
  225.                loss of quality.
  226.              - If you DO NOT set the FAST keyword, the sample rate of the
  227.                output file will be limited to 28kHz and downsampled
  228.                automaticlly if nessecary.
  229.              I recommend to keep the original file if you have enough
  230.              space. If you don't you may be disappointed of your converted
  231.              8 bit sounds when you buy a better sound system!
  232.  
  233. FILTER/K(*) FILTER=ON  : Enable audio filter for playback
  234.             FILTER=OFF : Disable audio filter for playback
  235.             FILTER=AUTO: Turn filter on or off depending on sample rate
  236.             If you don't specify this keyword Play16 will leave the
  237.             hardware registers of the audiofilter completely untouched.
  238.  
  239. LOOPS/N     Determines the number of loops to be played.
  240.             Default is 1 loop. (Play the sound once.)
  241.             LOOPS=0 means infinite number of loops.
  242.  
  243.  
  244. Advanced Options:
  245.  
  246. WINDOW/K(*)   Specify output window for Workbench startup. This Keyword can
  247.               only be used in the ToolType entries of the Play16 icon itself.
  248.               If you don't set this, the hardcoded default will be used.
  249.  
  250. SCREENMODE/N  Type of screen to open during playback. If you set
  251. (*)           SCREENMODE=0, a standard productivity screen will
  252.               be opened.
  253.  
  254. PATH/K        Set the default path for the filerequester. In the command
  255.               line, specifying just a path instead of a filename has the
  256.               same effect.
  257.  
  258. SINGLE/S      Use only one buffer rather then two and load all data into
  259.               memory before playback.
  260.  
  261. PRIORITY/N    Set Play16's task priority. May vary from -25 to 25, default
  262.               is 1.
  263.  
  264. MULTIPLE/S    Open the filerequester again, after all files have been
  265.               played.
  266.  
  267. BUFFER/N      Buffersize in samples. May vary from 32768 to 131072. The
  268.               amount of allocated memory also depends on whether the sound
  269.               is mono or stereo, 8 bit or 16 bit.
  270.               Default is 65536 samples, values are rounded to multiples of
  271.               32768.
  272.               Note that it is useless to modify this value when in single
  273.               buffer mode :)
  274.  
  275. PRELOAD/S     Load enough data into memory for immediate start of playback
  276.               at a keypress
  277.  
  278. RAW/S         Disable autodetect and tell Play16 what the actual format of
  279.               the sound data is.
  280.               However, if Play16 can't detect the filetype it will switch
  281.               to RAW mode automatically. If you don't want this to happen
  282.               you can specify STRICT:
  283.  
  284. STRICT/S      Play only files that are supported by the autodetect routine
  285.               Use this if you don't want to get scared by the sudden noisy
  286.               output when trying to play back other data than sound :-)
  287.  
  288. Examples:
  289.  
  290. a) Play16 music.wav
  291.     Simply play the file called music.wav once and directly from harddisk.
  292.  
  293. b) Play16 music.wav SINGLE
  294.     Same as above but load all data into memory before playback. Use this
  295.     when loading soundfiles from floppy disk.
  296.  
  297. c) Play16 music.wav SINGLE VERBOSITY=1
  298.     Same as b, but with additional information being printed out.
  299.  
  300. d) Play16 rhythm.wav LOOPS=10
  301.         Play the rhythm as a continuous loop, i.e. over and over again (10 times)
  302.  
  303. e) Play16 explosion.wav SINGLE PRELOAD
  304.     Load the complete explosion sound into memory, then wait for you to hit
  305.     <return> before playback.
  306.  
  307. f) Play16 MyFavouriteTune.wav FAST OUTPUT=8SVX
  308.     Convert the given file to IFF-8SVX without changing the sample rate.
  309.  
  310. g) Play16 MyFavouriteTune.wav OUTPUT=8SVX
  311.     Same as f but limit the sample rate of the converted file to 28kHz!
  312.  
  313. The following options tell Play16 what parameters to use when in RAW mode.
  314. This happens either if you set the RAW keyword or if Play16 could not
  315. identify the file and STRICT was _not_ set.
  316.  
  317.  
  318. Options when in RAW mode:
  319.  
  320. FREQ/N      Sampling frequency in Hz
  321. TRACKS/N    Number of tracks, 1 for mono, 2 for stereo
  322. BITS/N      Resolution in bits, may be 8 or 16
  323. HEADER/N    Length of header: This is the number of bytes to be skipped
  324.                               at the beginning of the file.
  325. UNSIGNED/S  Data is unsigned, not signed (only valid for  8 bit sounds)
  326. INTEL/S     Data is in Intel format      (only valid for 16 bit sounds)
  327. ULAW/S      Data is compressed using the uLaw compression scheme
  328.  
  329. The default settings are: 22050 Hz, mono, 8 bits, no header.
  330.  
  331.  
  332.  
  333. How do I use this RAW mode?
  334. ---------------------------
  335. Umm, err, difficult to explain, even harder to understand...
  336. Well, if you know the data format of the soundfile, simply set RAW, FREQ,
  337. TRACKS, BITS, UNSIGNED and INTEL accordingly. If you don't, the only
  338. way to find it out is by trial and error :) Here are some tips to make
  339. it a bit easier:
  340.  
  341. Don't set HEADER to an odd number. (Leave it at 0, first.)
  342. If you set BITS to 16 and hear nothing but noise, try to set INTEL.
  343. If you set BITS to 8 and the sound is distorted, try to set UNSIGNED.
  344. If the above does not help, try different combinations of BITS, INTEL
  345. and UNSIGNED.
  346.  
  347. If you manage to get a recognisable sound output which is either too
  348. fast or too slow, start experimenting on TRACKS and FREQ.
  349.  
  350. If you want to play known files and raw ones without changing the command
  351. line, simply specify all you know about the raw data and leave out the
  352. RAW and the STRICT keyword. If Play16 can indentify the file it will use
  353. its parameters. If the filetype is unknown your specified parameters will
  354. be used instead.
  355.  
  356.  
  357. Legal stuff
  358. -----------
  359. Play16 is copyrighted freeware. It may be distributed freely as long as
  360. no modifications are made to the executable and this document. A nominal
  361. fee may be asked to cover distribution costs.
  362.  
  363. Play16 may not be used for any commercial purposes or included with any
  364. commercial product without the written permission of the author.
  365.  
  366. No responsibilities are taken for damaged speakers, amplifiers, Amigas
  367. or any other components or data involved while using Play16.
  368.  
  369. Although I've done some beta testing I can't guarantee that Play16 will
  370. not crash! If you find any bugs, let me know.
  371.  
  372. It is NOT the fault of MacroSystem NOR does it represent the quality of
  373. their products if the MPro output or the maestix.library should fail.
  374.  
  375.  
  376. Miscellaneous
  377. -------------
  378. I don't claim Play16 to be fast. I've done some optimizing - but because
  379. the loader/converter module is a universial one, more data is actually
  380. being moved around different memory blocks than needed for playback.
  381. However, I've implemented separate optimized routines for 8 bit and
  382. for 14/16 bit.
  383.  
  384. * Please note that English is not my native language :)
  385.  
  386. I can be reached at...
  387.  
  388. Internet: wenzel@unixserv.rz.fh-hannover.de (preferred)
  389.           Thomas_Wenzel@aventure.fido.de
  390. Fido:     2:2432/350.28 or 2:241/1035.6
  391.           Mail routing _is_sometimes_ unreliable in FidoNet :-(
  392.  
  393. If you use this program, please send me a mail. I'd like to know how many
  394. people are interested in it at all.
  395.  
  396.  
  397. History
  398. -------
  399. V0.5ß   - Initial beta test release
  400.  
  401. V0.6ß   - Optimized the code a bit.
  402.  
  403. V0.7ß   - Fixed some severe bugs that caused Play16 to crash when trying
  404.           to load corrupted files.
  405.  
  406. V0.8ß   - Play16 can now be stopped by pressing ctrl-c during playback. The
  407.           buffer that is currently being played will be finished first.
  408.         - Automatic filter control depending on sample rate.
  409.  
  410. V0.9ß   - Added 'loop'-option. Sample can be played several times.
  411.         - All time consuming routines now in hand optimized assembler code.
  412.  
  413. V1.0ß   - Play16 now uses standard OS2.x commandline template.
  414.           Thanks to Kai for persuading me to do this :)
  415.  
  416. V1.0    - Done some minor bugfixes.
  417.  
  418. V1.1    - Oops! Play16 caused some Enforcer hits. Fixed that.
  419.           Thanks to Rod Schnell for reporting it.
  420.         - Added 'single'-option. Sound can be loaded completely into memory
  421.           before playing. No looping possible in this case yet!
  422.         - Playback time in minutes:seconds displayed if verbose >= 1
  423.         - uLaw decompression for WAVE-Files, using a decoding table
  424.           for maximum speed (didn't do much testing on it, hope it works!)
  425.         - MAUD filetype support (why do there have to be so many formats?)
  426.         - AIFF filetype support
  427.         - ctrl-c now stops playback immediately.
  428.           Thanks to Marc for some programming tips about that.
  429.  
  430. V1.2    - IFF-8SVX filetype support (only uncompressed files!)
  431.         - RAW data support: _Any_ data can be played
  432.         - Preload feature added
  433.         - Fixed a bug that caused illegal memory access (hopefully)
  434.           Thanks to Ignatios Souvatzis for reporting it.
  435.         - Improved chunk handling
  436.  
  437. V1.3    - 14 bit output (finally!)
  438.         - Any file Play16 can't recognise is considered raw data unless
  439.           you set the STRICT keyword
  440.         - Fixed a bug in WAV filetype length determination
  441.         - Advanced audiofilter control / original state will be restored
  442.           after playback
  443.         - More information about sound (AUTHOR or ANNO-Chunk) is being
  444.           printed out if VERBOSE>=1. However, Play16 will *not* search
  445.           the whole file for that string. If it doesn't come before the
  446.           sound data -- bad luck :-)
  447.  
  448. V1.3a   - Bugfix in chunk handling routine: Chunks with an odd length
  449.           were treated incorrectly. This bug accompanied all versions
  450.           of Play16, even V1.0. However, I decided to release a fix now
  451.           instead of letting you wait until V1.4 is finished.
  452.  
  453. V1.4    - Wildcard and multiple file support
  454.         - Environment variable support (partial)
  455.         - A filerequester will pop up if no filename is given
  456.         - Workbench support, including icon with tooltype entries
  457.         - Maestro Pro output, using Richard Körber's Maestix package
  458.         - Calibrated 14 bit output, using Christian Buchner's
  459.           CyberSound package
  460.         - IFF-8SVX file dump
  461.         - Creative VOC support (currently only 1st data block)
  462.           (This format crazy :-))
  463.         - Closing the output window now stops playback, too
  464.         - Looping now for single mode as well, LOOPS=0 won't cause
  465.           a severe crash any more
  466.           Thanks to Andy Church for reporting it.
  467.         - Open a screen during playback, e.g. productivity for fast DMA
  468.         - German docs
  469.  
  470. V1.5    - Fixed a bug that caused enforcer hits when running Play16
  471.           from CLI
  472.         - Changed the depth of Play16's productivity screen to 1 bitplane
  473.           to reduce CPU- and DMA-load
  474.         - "Play16 <path>" now opens a filerequester pointing to the
  475.           specified path. The new PATH tooltype does the same.
  476.         - Fixed mono playback of raw tracks.
  477.         - uLaw decompression for MAUD, too
  478.         - Fibonacci Delta decompression for 8SVX, thanks to Ralph Wermke.
  479.  
  480. V1.6    - Improved the V34 performance. (whoops, wrong file! :-)))
  481.         - A one-plane-screen will now be used for CLI mode as well.
  482.         - Task priority is now reset to 0 at exit.
  483.         - Files with additional data after the sound chunk are now being
  484.           played correctly.
  485.         - CTRL-D now skips the current sound and starts playing
  486.           the next one.
  487.         - ASL library will only be opened if a filerequester is really
  488.           needed. Thanks to all who suggested to do this.
  489.         - New option: Volume (only for Paula8 mode)
  490.         - New option: Multiple (only if filerequester pops up)
  491.         - No more chunks of odd length in 8SVX dump
  492.         - MS-ADPCM decompression for WAV files (still experimental)
  493.         - RAW option works now as a Tooltype entry as well
  494.  
  495. Future plans
  496. ------------
  497. - Supporting loops stored within 8SVX files
  498. - Better Creative-VOC support
  499. - ADPCM decompression for other filetypes as well (e.g. ZyXEL)
  500. - some of the file types saved by Macintosh software (e.g. Sound-Designer)
  501.   (Please let me know if you really ned this. I think AIFF should be
  502.   sufficient.)
  503. - Datatypes support
  504.  
  505. Known bugs
  506. ----------
  507. Looping of Fibonacci Delta sounds may be distorted.
  508.  
  509. Large VOC sounds can't be played completely.
  510.  
  511. Credits
  512. -------
  513. Thanks go to the following persons:
  514.  
  515. Kai Stuke         for many vital hints on C programming and the Amiga
  516.                   audio device and for beta testing this program.
  517.  
  518. Marc Führer       for doing some beta testing as well, giving valuable
  519.                   hints on optimizing the code and translating this document
  520.                   into German.
  521.  
  522. Clete Baker       for supplying the AIFF- and SDII specs.
  523.  
  524. Richard Körber    for writing the Maestix Library and making it freeware.
  525.  
  526. Christian Buchner for his research and ideas on how to improve the
  527.                   14bit output by calibrating the DACs individually.
  528.  
  529. And to all the people who wrote me!
  530.